@inkeep/open-knowledge 0.62.0-beta.2 → 0.62.0-beta.21

package/dist/{acp-harness-probe-CsOd2HY8.mjs → acp-harness-probe-kUb2Kidl.mjs}

@@ -1,6 +1,6 @@
-import{pt as e}from"./sleep-DhRrtbfG.mjs";import{Pi as t}from"./src-B_6tF_Gx.mjs";import{F as n,M as r,N as i}from"./fs-traced-2B_-YK-g.mjs";import{b as a,g as o,m as s,p as c,s as l}from"./resolve-project-root-BjH69ZD8.mjs";import{S as ee,T as u,d,o as f,v as p,x as te}from"./init-1WSRoxGv.mjs";import{t as m}from"./is-object-Bw0-z8qH.mjs";import{execFileSync as ne,spawn as h}from"node:child_process";import{basename as re,dirname as g,join as _,resolve as v,win32 as y}from"node:path";import{existsSync as b,mkdirSync as x,readFileSync as S,readdirSync as C,statSync as ie,writeFileSync as w}from"node:fs";import{homedir as T}from"node:os";var E=e();const D=`open-knowledge`;function O(e){try{e()}catch{}}var k=class{backend=`keyring`;constructor(e){this.onKeychainRead=e}async get(e){let{Entry:t}=await import(`@napi-rs/keyring`),n;try{n=new t(D,e).getPassword()}catch(t){return O(()=>this.onKeychainRead?.({kind:`read-error`,host:e,error:t instanceof Error?t.name:`unknown`})),null}if(n==null)return O(()=>this.onKeychainRead?.({kind:`absent`,host:e})),null;try{return JSON.parse(n)}catch{return O(()=>this.onKeychainRead?.({kind:`corrupt-entry`,host:e,error:`corrupt-entry`})),null}}async set(e,t,n,r){let{Entry:i}=await import(`@napi-rs/keyring`),a=new i(D,e),o={login:t,token:n,...r};a.setPassword(JSON.stringify(o))}async clear(e){let{Entry:t}=await import(`@napi-rs/keyring`);try{new t(D,e).deletePassword()}catch{}}},A=class{backend=`file`;authFile;constructor(e){this.authFile=e??_(T(),`.ok`,`auth.yml`)}read(){if(!b(this.authFile))return{};try{return(0,E.parse)(S(this.authFile,`utf-8`))??{}}catch(e){let t=e instanceof Error?e.message:`unknown error`;return process.stderr.write(`[auth] Failed to parse ${this.authFile}: ${t}. Starting with empty credentials.\n`),{}}}write(e){let t=g(this.authFile);b(t)||x(t,{recursive:!0,mode:448}),w(this.authFile,(0,E.stringify)(e),{mode:384})}async get(e){return this.read()[e]??null}async set(e,t,n,r){let i=this.read();i[e]={login:t,token:n,...r},this.write(i)}async clear(e){let t=this.read();delete t[e],this.write(t)}},ae=class{backend=`keyring`;constructor(e,t){this.keychain=e,this.file=t}async get(e){let t=await this.keychain.get(e);if(t!=null)return t;let n=await this.file.get(e);if(n==null)return null;try{await this.keychain.set(e,n.login,n.token,{gitProtocol:n.gitProtocol,name:n.name,email:n.email}),await this.file.clear(e),process.stderr.write(`[auth] migrated ${e} credential from ~/.ok/auth.yml to the OS keychain\n`)}catch{}return n}set(e,t,n,r){return this.keychain.set(e,t,n,r)}async clear(e){await this.keychain.clear(e),await this.file.get(e)!=null&&await this.file.clear(e)}};async function j(e,t){try{let{Entry:n}=await import(`@napi-rs/keyring`);return new n(D,`__probe__`),process.stderr.write(`[auth] token storage: OS keychain
+import{pt as e}from"./sleep-D4NlDISj.mjs";import{Pi as t}from"./src-B51qQNNF.mjs";import{F as n,M as r,N as i}from"./fs-traced-Dm4NQ6S5.mjs";import{b as a,g as o,m as s,p as c,s as l}from"./resolve-project-root-D42xTuDS.mjs";import{S as ee,T as u,d,o as f,v as p,x as te}from"./init-BdoxPt_G.mjs";import{t as m}from"./is-object-Bw0-z8qH.mjs";import{execFileSync as ne,spawn as h}from"node:child_process";import{basename as re,dirname as g,join as _,resolve as v,win32 as y}from"node:path";import{existsSync as b,mkdirSync as x,readFileSync as S,readdirSync as C,statSync as ie,writeFileSync as w}from"node:fs";import{homedir as T}from"node:os";var E=e();const D=`open-knowledge`;function O(e){try{e()}catch{}}var k=class{backend=`keyring`;constructor(e){this.onKeychainRead=e}async get(e){let{Entry:t}=await import(`@napi-rs/keyring`),n;try{n=new t(D,e).getPassword()}catch(t){return O(()=>this.onKeychainRead?.({kind:`read-error`,host:e,error:t instanceof Error?t.name:`unknown`})),null}if(n==null)return O(()=>this.onKeychainRead?.({kind:`absent`,host:e})),null;try{return JSON.parse(n)}catch{return O(()=>this.onKeychainRead?.({kind:`corrupt-entry`,host:e,error:`corrupt-entry`})),null}}async set(e,t,n,r){let{Entry:i}=await import(`@napi-rs/keyring`),a=new i(D,e),o={login:t,token:n,...r};a.setPassword(JSON.stringify(o))}async clear(e){let{Entry:t}=await import(`@napi-rs/keyring`);try{new t(D,e).deletePassword()}catch{}}},A=class{backend=`file`;authFile;constructor(e){this.authFile=e??_(T(),`.ok`,`auth.yml`)}read(){if(!b(this.authFile))return{};try{return(0,E.parse)(S(this.authFile,`utf-8`))??{}}catch(e){let t=e instanceof Error?e.message:`unknown error`;return process.stderr.write(`[auth] Failed to parse ${this.authFile}: ${t}. Starting with empty credentials.\n`),{}}}write(e){let t=g(this.authFile);b(t)||x(t,{recursive:!0,mode:448}),w(this.authFile,(0,E.stringify)(e),{mode:384})}async get(e){return this.read()[e]??null}async set(e,t,n,r){let i=this.read();i[e]={login:t,token:n,...r},this.write(i)}async clear(e){let t=this.read();delete t[e],this.write(t)}},ae=class{backend=`keyring`;constructor(e,t){this.keychain=e,this.file=t}async get(e){let t=await this.keychain.get(e);if(t!=null)return t;let n=await this.file.get(e);if(n==null)return null;try{await this.keychain.set(e,n.login,n.token,{gitProtocol:n.gitProtocol,name:n.name,email:n.email}),await this.file.clear(e),process.stderr.write(`[auth] migrated ${e} credential from ~/.ok/auth.yml to the OS keychain\n`)}catch{}return n}set(e,t,n,r){return this.keychain.set(e,t,n,r)}async clear(e){await this.keychain.clear(e),await this.file.get(e)!=null&&await this.file.clear(e)}};async function j(e,t){try{let{Entry:n}=await import(`@napi-rs/keyring`);return new n(D,`__probe__`),process.stderr.write(`[auth] token storage: OS keychain
 `),O(()=>t?.onBackendSelected?.({backend:`keyring`})),new ae(new k(t?.onKeychainRead),new A(e))}catch(n){let r=n instanceof Error?`${n.name}: ${n.message}`:String(n);return process.stderr.write(`[auth] token storage: file (~/.ok/auth.yml) — OS keychain unavailable: ${r}\n`),O(()=>t?.onBackendSelected?.({backend:`file`,reason:r})),new A(e)}}function M(e){let t=null;return function(){if(t)return t;let n=2e3;return t=(async()=>{let t=null,r=new Promise(r=>{t=setTimeout(()=>{process.stderr.write(`[auth] token storage: keyring init exceeded ${n}ms; falling back to file (~/.ok/auth.yml)\n`),r(new A(e))},n)});try{return await Promise.race([j(e),r])}catch{return new A(e)}finally{t!==null&&clearTimeout(t)}})(),t}}function N(e){let t=M(e);return{async get(e){let n=await(await t()).get(e);return n===null?null:{token:n.token}}}}function P(e){let t=M(e);return{backend:`file`,async get(e){return(await t()).get(e)},async set(e,n,r,i){return(await t()).set(e,n,r,i)},async clear(e){return(await t()).clear(e)}}}async function F(e,t){let n=[],r=new A(t);await r.get(e)!=null&&(await r.clear(e),n.push(`file`));let i;try{let{Entry:t}=await import(`@napi-rs/keyring`);new t(D,`__probe__`);let r,a=await new k(e=>{e.kind===`read-error`&&(r=e.error??`read-error`)}).get(e);if(r!==void 0)i=r;else if(a!=null)try{new t(D,e).deletePassword(),n.push(`keychain`)}catch(e){i=e instanceof Error?e.name:`delete-error`}}catch{}return{touched:n,keychainError:i}}const I=[`/opt/homebrew/bin/gh`,`/usr/local/bin/gh`,`/opt/local/bin/gh`,`/snap/bin/gh`,`/usr/bin/gh`],L={encoding:`utf-8`,stdio:[`ignore`,`pipe`,`pipe`],timeout:5e3,windowsHide:!0};function R(e,t={}){let n=t._exec??ne,r=t._fileExists??b,i=[`auth`,`token`,...e?[`--hostname`,e]:[]],a=[`gh`,...I.filter(r)];for(let e of a)try{let t=n(e,i,L).toString().trim();if(t.length>0)return{available:!0,token:t}}catch{}return{available:!1}}function z(e){let t={...e};return delete t.ELECTRON_RUN_AS_NODE,t}function B(e){let t=e?.code;return t===`ENOENT`||t===`EACCES`||t===`EPERM`?{ok:!1,reason:`not-installed`}:{ok:!1,reason:`spawn-error`}}function V(e){return t({detached:!0,stdio:`ignore`,shell:!1,env:z(e)})}function H(e,t,n={}){let r=(n.spawn??h)(e,[...t],V(n.env??process.env));return r.unref(),r}function U(e,t,n={}){let r=n.spawn??h,i=n.timeoutMs??2e3;return new Promise(a=>{let o=!1,s=e=>{o||(o=!0,a(e))},c=setTimeout(()=>s({ok:!1,reason:`timeout`}),i);try{let i=r(e,[...t],V(n.env??process.env));i.once(`error`,e=>{clearTimeout(c),s(B(e))}),i.once(`spawn`,()=>{clearTimeout(c),s({ok:!0})});try{i.unref()}catch{}}catch(e){clearTimeout(c),s(B(e))}})}const W=`com.inkeep.open-knowledge`,G=`OpenKnowledge.app`,K=`/Applications/${G}`;function q(){return{platform:process.platform,env:process.env,execPath:process.execPath,isTTY:process.stdout.isTTY,statSync:e=>{try{return ie(e,{throwIfNoEntry:!1})??null}catch{return null}}}}function oe(e){if(e.env.ELECTRON_RUN_AS_NODE===`1`){let t=/(.+?\.app)\/Contents\/MacOS\//.exec(e.execPath);if(t?.[1])return t[1]}if(J(e,K))return K;let t=_(e.homeDir??T(),`Applications`,G);return J(e,t)?t:null}function J(e,t){return Y(e,_(t,`Contents`,`MacOS`,`OpenKnowledge`))}function Y(e,t){try{let n=e.statSync(t);return n&&typeof n.isFile==`function`?n.isFile():!1}catch{return!1}}const se=[`@inkeepopen-knowledge-desktop`,`OpenKnowledge`];function ce(e){if(e.env.ELECTRON_RUN_AS_NODE===`1`&&/\\OpenKnowledge\.exe$/i.test(e.execPath))return e.execPath;let t=e.env.LOCALAPPDATA;if(t)for(let n of se){let r=y.join(t,`Programs`,n,`OpenKnowledge.exe`);if(Y(e,r))return r}return null}function le(e){if(e.env.ELECTRON_RUN_AS_NODE===`1`&&e.execPath.endsWith(`/openknowledge`))return e.execPath;let t=`/opt/OpenKnowledge/openknowledge`;return Y(e,t)?t:null}function ue(e){if(e.env.OK_FORCE_BROWSER===`1`)return{available:!1,reason:`force-browser`};if(e.platform!==`darwin`&&e.platform!==`win32`&&e.platform!==`linux`)return{available:!1,reason:`unsupported-platform`};let t;try{t=e.platform===`darwin`?oe(e):e.platform===`win32`?ce(e):le(e)}catch{return{available:!1,reason:`stat-error`}}return t?e.env.OK_FORCE_DESKTOP===`1`?{available:!0,reason:`available`,bundlePath:t}:!(e.isTTY===!0||e.platform===`win32`&&e.isTTY===void 0&&!e.env.CI)||e.env.SSH_CONNECTION||e.env.SSH_TTY||e.platform===`linux`&&!e.env.DISPLAY&&!e.env.WAYLAND_DISPLAY?{available:!1,reason:`headless`,bundlePath:t}:{available:!0,reason:`available`,bundlePath:t}:{available:!1,reason:`no-bundle`}}function de(e,t){let n=e.log??(e=>console.error(e)),r=e.platform??process.platform;if(n("Launching OpenKnowledge desktop (use `ok start` for the browser server, or `OK_FORCE_BROWSER=1` to always skip)"),r===`darwin`){H(`open`,[`-b`,W],{spawn:e.spawn});return}let i=t?.bundlePath;if(!i){n(`Desktop launch skipped: no resolved desktop executable (caller bug).`);return}H(i,[],{spawn:e.spawn})}function fe(e=`no-bundle`){switch(e){case`no-bundle`:return`Desktop app not found (checked the standard install locations for this OS). Install it from https://openknowledge.ai/download, or omit --mode for browser mode.`;case`darwin-only`:case`unsupported-platform`:return`Desktop app is not available on this platform. Use --mode=browser, or omit --mode for the server fallback.`;case`headless`:return`Desktop launch is gated in headless contexts (CI, SSH, non-TTY stdout). Set OK_FORCE_DESKTOP=1 to override, or use --mode=browser.`;case`force-browser`:return`OK_FORCE_BROWSER=1 is set — desktop dispatch is disabled. Unset it to use --mode=app.`;case`stat-error`:return`Failed to inspect the desktop install (filesystem error). Check permissions or use --mode=browser.`;case`available`:return`Desktop app appears available but launch dispatch did not fire (caller bug).`}}function X(e,t){let n=v(e),r=t===void 0?a():a({home:t,env:{}});return{cwd:n,bridgePath:l.pi.projectConfigPath?.(n)??``,trustPath:_(r,`trust.json`)}}function Z(e,t,n){let r=f(l.pi,e,n,t);if(r.kind===`absent`)return{state:`absent`,text:null};if(r.kind!==`present`)return{state:`unreadable`,text:null};let i=r.entry,a=Array.isArray(i.args)&&typeof i.args[0]==`string`?i.args[0]:null;return s(i)?{state:`own-current`,text:a}:ee(i)?{state:`own-stale`,text:a}:{state:`foreign`,text:a}}function Q(e,t){let n;try{n=S(e,`utf-8`)}catch(e){let t=e.code;return t===`ENOENT`||t===`ENOTDIR`?{state:`untrusted`,entries:{},trailingNewline:!1}:{state:`unreadable`,entries:null,trailingNewline:!1}}if(n.trim()===``)return{state:`untrusted`,entries:{},trailingNewline:!1};let r;try{r=JSON.parse(n)}catch{return{state:`unreadable`,entries:null,trailingNewline:!1}}return m(r)?{state:r[t]===!0?`trusted`:`untrusted`,entries:r,trailingNewline:n.endsWith(`
 `)}:{state:`unreadable`,entries:null,trailingNewline:!1}}function pe(e,t){let n=X(e,t),r=Z(n.cwd,n.bridgePath,t).state,i=Q(n.trustPath,n.cwd).state;return{...n,bridge:r,trust:i,bridgeLoadable:(r===`own-current`||r===`own-stale`)&&i===`trusted`,otherExtensions:$(n.bridgePath).names}}function $(e){let t=g(e),n=re(e);try{return{names:C(t).filter(e=>e!==n&&e.endsWith(`.ts`)).sort(),verified:!0}}catch(e){let t=e.code;return{names:[],verified:t===`ENOENT`||t===`ENOTDIR`}}}async function me(e,t={mode:`published`},n){let r=X(e,n),i=Z(r.cwd,r.bridgePath,n);if(i.state===`foreign`)return{...r,ok:!1,bridge:`refused-foreign`,trust:`skipped`};if(i.state===`unreadable`)return{...r,ok:!1,bridge:`refused-unreadable`,trust:`skipped`};let a;if(i.state===`absent`)a=`written`;else{let e;try{e=te(t)}catch{e=void 0}a=e!==void 0&&i.text===e?`unchanged`:`refreshed`}if(a!==`unchanged`){let e=p(l.pi,r.cwd,t,n,r.bridgePath);if(e.action!==`written`&&e.action!==`overwritten`)return{...r,ok:!1,bridge:`failed`,trust:`skipped`,error:e.error??`bridge write ${e.action}`}}let o=await he(r.trustPath,r.cwd);return{...r,ok:o.action===`already-trusted`||o.action===`added`,bridge:a,trust:o.action,...o.error===void 0?{}:{error:o.error}}}async function he(e,t){try{x(g(e),{recursive:!0})}catch(e){return{action:`failed`,error:e instanceof Error?e.message:String(e)}}let i={action:`added`};try{await r(`${e}.lock`,async()=>{let r=Q(e,t);if(r.state===`trusted`){i.action=`already-trusted`;return}if(r.entries===null){i.action=`refused-unreadable`;return}let a={...r.entries,[t]:!0},o=JSON.stringify(a,null,2)+(r.trailingNewline?`
 `:``),s=u(e);n(e,o,s===void 0?void 0:{mode:s}),i.action=`added`})}catch(e){return{action:`failed`,error:e instanceof Error?e.message:String(e)}}return i.action===`refused-unreadable`?{action:`refused-unreadable`,error:`trust store is not a readable JSON object`}:{action:i.action}}function ge(e,t){let r=X(e,t),a=$(r.bridgePath);if(!a.verified)return{action:`kept-unverified`,error:`could not read the Pi extensions folder`};if(a.names.length>0)return{action:`kept-shared`};if(!b(r.trustPath))return{action:`not-present`};let o={action:`removed`};try{i(`${r.trustPath}.lock`,()=>{let e=Q(r.trustPath,r.cwd);if(e.entries===null){o.action=e.state===`unreadable`?`refused-unreadable`:`not-present`;return}if(!(r.cwd in e.entries)){o.action=`not-present`;return}let t={...e.entries};delete t[r.cwd];let i=JSON.stringify(t,null,2)+(e.trailingNewline?`
 `:``),a=u(r.trustPath);n(r.trustPath,i,a===void 0?void 0:{mode:a}),o.action=`removed`})}catch(e){return{action:`failed`,error:e instanceof Error?e.message:String(e)}}return o.action===`refused-unreadable`?{action:`refused-unreadable`,error:`trust store is not a readable JSON object`}:{action:o.action}}function _e(e){return e===`opencode`?o:c}function ve(e,t,n){let r=l[e],i=_e(e),a=[],o=r.projectConfigPath?.(t);o!==void 0&&a.push({scope:`project`,configPath:o});try{a.push({scope:`user`,configPath:r.configPath(t,n)})}catch{}for(let o of a){let a=d(r,t,n,o.configPath);if(a!==null&&i(a))return{editorId:e,scope:o.scope,configPath:o.configPath}}return null}export{W as a,de as c,U as d,R as f,P as g,N as h,ge as i,fe as l,j as m,me as n,q as o,F as p,pe as r,ue as s,ve as t,H as u};
-//# sourceMappingURL=acp-harness-probe-CsOd2HY8.mjs.map
+//# sourceMappingURL=acp-harness-probe-kUb2Kidl.mjs.map

package/dist/assets/skills/packs/codebase-wiki/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "codebase-wiki",
+  "description": "Starter pack: a living wiki for a codebase",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/entity-vault/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "entity-vault",
+  "description": "Starter pack: an entity vault knowledge base",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/knowledge-base/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "knowledge-base",
+  "description": "Starter pack: a general team knowledge base",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/okf/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "okf",
+  "description": "Starter pack: Open Knowledge Format (OKF) guidance",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/plain-notes/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "plain-notes",
+  "description": "Starter pack: plain markdown notes",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/software-lifecycle/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "software-lifecycle",
+  "description": "Starter pack: specs, stories, and reports for software work",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/worldbuilding/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "worldbuilding",
+  "description": "Starter pack: worldbuilding for fiction projects",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/packs/writing-pipeline/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "writing-pipeline",
+  "description": "Starter pack: a drafting and editing pipeline",
+  "author": {
+    "name": "Inkeep"
+  },
+  "repository": "https://github.com/inkeep/open-knowledge-skills",
+  "keywords": ["openknowledge", "starter-pack"]
+}

package/dist/assets/skills/write-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-knowledge-write-skill
-description: "Use when the user wants to create, author, write, or design a new Agent Skill (a SKILL.md) — for OpenKnowledge or for their editors — including requests like 'help me write a skill', 'make a skill that…', 'turn this workflow into a skill', or improving an existing skill's triggering and discipline. Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt. Covers choosing scope (project vs global), the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors."
+description: "Use when the user wants to create, author, write, or design a new Agent Skill (a SKILL.md) — for OpenKnowledge or for their editors — including requests like 'help me write a skill', 'make a skill that…', 'turn this workflow into a skill', or improving an existing skill's triggering and discipline. Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt. Covers choosing scope (project vs global), authoring inside a plugin or skills-distribution repo (write in the repo's own layout, never install), the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors."
 compatibility: "OpenKnowledge project recommended (uses the `write` / `edit` / `install` MCP verbs). Authoring + validation are pure file ops; live preview + eval want a running server (`ok start`)."
 metadata:
   author: "Inkeep"
@@ -80,6 +80,19 @@ Default heuristic: inside an OK project and the task is specific to it → **pro
 "for all my work / globally" → **global**; otherwise ask one question. State the
 choice and its consequence before writing.
 
+**Developing a skills repo or plugin? Then NEITHER scope applies.** If the repo
+you are working in is itself a skill *distribution* — a plugin (e.g. a
+`.claude-plugin/` manifest or marketplace listing) or a catalog repo that
+shelves skills as `skills/<name>/` for others to import — the skill you are
+authoring is a **product of that repo**, not an installation into it. Write it
+in the repo's own layout, beside its sibling skills, following the format the
+repo already uses. Do **not** place it under `.claude/skills/` or
+`.agents/skills/` here, and do **not** `install` it: consumers get it by
+installing the plugin or importing from the repo, and the plugin's own repo
+loads nothing from itself. `install` is only for skills the *current* project
+or user should load. If you are unsure whether the repo is a distribution or a
+consumer, ask — writing to the wrong place ships a skill nobody can find.
+
 ## Stage 3 — Plan the contents
 
 - **Body** = the durable, reusable instructions — under ~500 lines. If it's